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Foreword 



rd , 



This Technical Specification has been produced by the 3 Generation Partnership Project (3GPP). 

3GPP acknowledges the contribution of the Parlay X web services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



,rd , 



The present document is part 8 of a multi-part deliverable covering the 3 Generation Partnership Project; Technical 
Specification Group Core Network and Terminals; Open Service Access (OSA); Parlay X Web Services, as identified 
below: 



Part 1: 


"Common"; 


Part 2: 


"Third party call"; 


Part 3: 


"Call Notification"; 


Part 4: 


"Short Messaging"; 


Parts: 


"Multimedia Messaging"; 


Part 6: 


"Payment"; 


Part?: 


"Account management"; 


Part 8: 


"Terminal Status"; 


Part 9: 


"Terminal location"; 


Part 10: 


"Call handling"; 


Part 11: 


"Audio call"; 


Part 12: 


"Multimedia conference"; 


Part 13: 


"Address list management" 


Part 14: 


"Presence". 
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1 Scope 

The present document is Part 8 of the Stage 3 Parlay X Web Services specification for Open Service Access (OS A). 

The OS A specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.127 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Terminal Status Web Service aspects of the interface. All aspects of the Terminal 
Status Web Service are defined here, these being: 

Name spaces. 

Sequence diagrams. 

Data definitions. 

Interface specification plus detailed method descriptions. 

Fault definitions. 

Service policies. 

WSDL Description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group. 

2 References 

The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulai-y for 3GPP Specifications". 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Services Access (OSA); Stage 1 ". 

[3] 3GPP TS 23. 127: "Virtual Home Environment (VHE) / Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X web services; Part 1: Common". 

3 Definitions and abbreviations 
3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 
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3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] apply. 

4 Detailed service description 

Terminal Status provides access to the status of a terminal through: 

• Request for the status of a terminal. 

• Request for the status of a group of terminals. 

• Notification of a change in the status of a terminal. 

The status of a terminal can be expressed as reachable, unreachable or busy - however not all terminals distinguish a 
busy status, so applications should be able to adapt to what information is available (using the service properties to 
determine available information). 

When a request for a group of terminals is made, the response may contain a full or partial set of results. This allows the 
service to provide results based on a number of criteria including number of terminals for which the request is made and 
amount of time required to retrieve the information. This allows the requester to initiate additional requests for those 
terminals for which information was not provided. 

5 Namespaces 

The data types are defined in the namespace: 

http://www.csapi.org/schema/parlayx/terminal_status/v2_2 
The TerminalStatus interface uses the namespace: 

http ://w w w . c s api.org/wsdl/parlayx/terminal_status/v2_2 
The TerminalStatusNotificationManager interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/terminal_status/notification_manager/v2_2 
The TerminalStatusNotification interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/terminal_status/notification/v2_2 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in 
XML Schema [5]. The use of the name 'xsd' is not semantically significant. 
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Sequence diagrams 



6.1 Terminal status query 

Pattern: Request / Response. 

When an application is interested in determining the status of a terminal device, it may provide a terminal device 
address, and receive the status for the device requested. 



Application 



Terminai 
Status 



getStatus 



^ 



Retrieve terminal status 



9ve 



<- 



Status 



Figure 1 
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6.2 Terminal status group query 



Pattern: Request / Response. 

When an application is interested in determining the status of a set of terminal devices, it may provide an array of 
terminal device addresses, including network managed group addresses, and receive the status for the set of devices 
requested. 



Application 



Terminal 
Status 



getStatusForGroup 



^ 



Process groups 

1 < 



Retrieve terminal status 



3ve 



Status list 



<- 



Figure 2 
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6.3 Terminal status notification 

Pattern: Application Correlated Multiple Notification. 

An application can be notified of a change in the status of terminal devices. When the status of a terminal device 
changes, a notification message will be sent to the application. 



Application 



: Terminal Status 



Notification 



: Notification 
Application 



: Notification 
Web Service 



Create correlation id 



^ 



startNotification 



At some later time, an event occurs to 
trigger the notification 



statusNotification 



^ 



At some later time, the notification may t^ 
be cancelled 



endNotification 



Figure 3 
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6.4 



Terminal Status Notification with Check Immediate 



In some applications, the terminal status notification will be used to watch for a specific status change. An example is a 
'call when available' service, where the terminal status is checked and determined to be not reachable or busy, and a 
notification is set up to notify the application when the terminal becomes reachable. Between the time that the original 
status determination and the time the notification is set up, the terminal status could change to reachable - thus the 
notification on change to reachable would not be sent. 

Using the check immediate flag, after the notification is established, the value of the terminal status wiU be determined, 
and if the criteria is matched then a notification will be sent immediately. The following sequence diagram shows this 
scenario. 



Application 



Terminal 
Status 



Terminal Status 
Notification 



: Notification 
Application 



getStatus 



: Notification 
Web Service 



i< 



Status 



Create correlation id 

1 < ^ 



startNotification with Qtieck Immediate = true 



Setlup notification 



«- 



Cfieck terminal status 



^- 



Apply count to notification 



<r- 



status Notification 



statusEnd 



Figure 4 
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This sequence shows: 

• The Enterprise AppHcation checks the status of a terminal, and receives its status (in this scenario receiving 
Unreachable or Busy. 

• The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the 
Enterprise Web Service when the terminal state becomes Reachable and the check immediate flag set to true. 

• Sets up the notification to monitor terminal status changes. 

• Check the current status of the terminal, and determine if the status matches the criteria. 

• In this case, the criteria matches, and a notification is delivered to the Enterprise Web Service. 

• The count of notifications is incremented and compared to the notification count limit. 

• In this case, a single notification was requested, and the end notification message is sent. 

• The startNotification operation completes. 

This scenario includes the full set of interactions in one sequence, which also shows that the notifications can be 
received concurrent with the creation of the notification. 



XML Schema data type definition 



7.1 



Status enumeration 



List of possible status values. 



Enumeration 


Description 


Reachable 


Terminal is reachable 


Unreachable 


Terminal is not reachable 


Busy 


Terminal is busy 



7.2 



RetrievalStatus enumeration 



Enumeration of the status items that are related to an individual retrieval in a set. 



Enumeration 


Description 


Retrieved 


Status retrieved, with result in CurrentStatus element. 


NotRetrieved 


Status not retrieved, CurrentStatus is not provided (does not indicate an error, no attempt may have 
been made). 


Error 


Error retrieving status. 
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7.3 



StatusData structure 



Data structure containing device identifier and its status. As this can be related to a query of a group of terminal devices, 
the ResultStatus element is used to indicate whether the information for the device was retrieved or not, or if an error 
occurred. 



Name 


Type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Address of the Terminal Device to whicli the status information 
applies. 


ReportStatus 


RetrievalStatus 


No 


Status of retrieval for this address. 


CurrentStatus 


Status 


Yes 


Status of terminal. It is only provided if ReportStatus=Retrieved. 


Errorlnformation 


common:ServiceError 


Yes 


If ReportStatus is Error, this is the reason for the error. Error due 
to privacy verification will be expressed as POL0002 in the 
ServiceError. 



7.4 



Statuslnformation structure 



Name 


Type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Address of the Terminal Device to which the status information applies. 


CurrentStatus 


Status 


No 


Status of terminal. 



8 



Web service interface definition 



8.1 Interface: TerminalStatus 

Request the status for a terminal or set of terminals. 

8.1.1 Operation: GetStatus 

This operation is intended to retrieve the status for a single terminal. The URI provided is for a single terminal, not a 
group URI. If a group URI is provided, a PolicyException will be returned to the application. 



8.1.1.1 



Input message: GetStatusRequest 



Part name 


Part type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Terminal to request status for 



8.1.1.2 



Output message: GetStatus Response 



Part name 


Part type 


Optional 


Description 


Result 


Status 


No 


Status for the terminal for which status was requested 



8.1.1.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: InvaUd input value. 
PohcyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 
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POL0002: Privacy error. 
POL0006: Groups not allowed. 



8.1.2 Operation: GetStatusForGroup 



The getStatusForGroup operation initiates a retrieval activity, where one or more terminals, or groups of terminals, may 
have their status determined. 

The Web Service may return a result set that does not include complete information, allowing the Web Service 
implementation to choose to deliver a partial set of results to accommodate other conditions, such as avoiding timeouts. 
In this case, the addresses for which no attempt was made to provide data will be marked NotRetrieved in the result for 
each address this applies to. 



8.1.2.1 



Input message: GetStatusForGroup Request 



Part name 


Part type 


Optional 


Description 


Addresses 


xsd:anyURI [1.. unbounded] 


No 


List of URIs to get status for, including group URIs 



8.1.2.2 



Output message: GetStatusForGroupResponse 



Part name 


Part type 


Optional 


Description 


Result 


StatusData [1 ..unbounded] 


No 


Set of results for the request 



8.1.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No vaUd addresses. 

• SVC0006: Invalid group. 
PohcyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0003: Too many addresses. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 

8.2 Interface: TerminalStatusNotificationManager 

Set up notifications for terminal status changes. 

8.2.1 Operation: StartNotification 

Notifications of status changes are made available to applications. The number and duration of notifications may be 
requested as part of the setup of the notification or may be governed by service policies, or a combination of the two. 

If Checklmmediate is set to true, then the notification will be set up, and then the current value of the terminal status 
will be checked. If the terminal status meets the criteria provided, a notification will be sent to the application. This 
notification will count against the count requested. This addresses the case where the status of the device changes 
during the time the notification is being set up, which may be appropriate in some applications. 
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The correlator provided in the reference must be unique for this Web Service at the time the notification is initiated, 
otherwise a ServiceException (SVC0005) will be returned to the application. 

If the frequency requested is more often than allowed by the service policy, then the value in the service policy will be 
used. If the duration requested exceeds the time allowed in the service policy, then the value in the service policy will 
be used. If the notification period (duration) ends before all of the notifications (count) have been delivered, then the 
notification terminates. In all cases, when the notifications have run their course (by duration or count), an end of 
notifications message will be provided to the application. 

Service policies may govern what count values can be requested, including maximum number of notifications allowed 
and whether unlimited notifications can be requested (i.e. either by not specifying the optional Count message part or by 
specifying it with a value of zero). If the count value requested is not in policy, a PolicyException (POL0004 or 
POL0005 as appropriate) will be returned. 



8.2.1.1 



Input message: StartNotification Request 



Part name 


Part type 


Optional 


Description 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


Addresses 


xsd:anyURI 
[1.. unbounded] 


No 


Addresses of terminals to monitor 


Criteria 


Status [1.. unbounded] 


No 


List of status values to generate notifications for (these 
apply to all addresses specified) 


Checl<lmmediate 


xsd:boolean 


No 


Check status immediately after establishing notification 


Frequency 


commoniTimelVletric 


No 


Maximum frequency of notifications (can also be 
considered minimum time between notifications) 


Duration 


commoniTimelVletric 


Yes 


Length of time notifications occur for, do not specify to use 
default notification time defined by service policy 


Count 


xsd:integer 


Yes 


IVIaximum number of notifications. For no maximum, either 
do not specify this part or specify a value of zero. 



8.2.1.2 



Output message: StartNotificationResponse 



Part name 


Part type 


Optional 


Description 


None 









8.2.1.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No vaUd addresses. 

• SVC0005: Duplicate correlator. 

• SVC0006: Invalid group. 
PoHcyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0003: Too many addresses. 

• POL0004: Unlimited notifications not supported. 

• POL0005: Too many notifications requested. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 



£75/ 



3GPP TS 29.199-08 version 6.2.0 Release 6 



16 



ETSI TS 129 199-8 V6.2.0 (2005-12) 



• POL0009: Invalid frequency requested. 

• POL0200: Busy criteria not supported. 

8.2.2 Operation: EndNotification 

The application may end a notification using this operation. Until this operation returns, notifications may continue to 
be received by the application. 

An end of notification (statusEnd) message will not be delivered to the application for a notification ended using this 
operation. 



8.2.2.1 



Input message: EndNotificationRequest 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator of request to end 



8.2.2.2 



Output message: EndNotification Response 



Part name 


Part type 


Optional 


Description 


None 









8.2.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• SVCOOOl: Service error. 

• SVC0002: Invalid input value. 
PoHcyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 



8.3 



Interface: TerminalNotification 



Notification interface to which notifications are delivered. 

8.3.1 Operation: StatusNotification 

When the status of monitored devices change, a notification is delivered to the application with the new status 
information for each of the devices. If a group identifier was used, the terminal device URI is provided, not the group 
URL 



8.3.1.1 



Input message: StatusNotification Request 



, Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification 


TerminalStatus 


Statuslnformation 
[1.. unbounded] 


No 


List of Statuslnformation elements describing address and 
new terminal status. 



8.3.1.2 



Output message: StatusNotification Response 



Part name 


Part type 


Optional 


Description 


None 
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8.3.1.3 

None. 



Referenced faults 



8.3.2 Operation: StatusError 



The status changed error message is sent to the appHcation to indicate that the notification is being cancelled by the 
Web Service. 



8.3.2.1 



Input message: StatusErrorRequest 



Part 
name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification. 


Address 


xsd:anyURI 


Yes 


Address of terminal if the error applies to an individual terminal, or not 
specified if it applies to the whole notification. 


Reason 


common:ServiceError 


No 


Reason notification is being discontinued. 



8.3.2.2 



Output message: StatusErrorResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.2.3 

None. 



Referenced faults 



8.3.3 Operation: StatusEnd 



The notifications have completed for this correlator. This message will be delivered when the duration or count for 
notifications have been completed. This message will not be delivered in the case of an error ending the notifications or 
deliberate ending of the notifications (using endNotification operation). 



8.3.3.1 



8.3.3.2 



Input message: StatusEndRequest 



Part name 


Part type 


Optional 


Description 


Correlator 


xsdistring 


No 


Correlator provided in request to set up this notification. 



Output message: StatusEndResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.3.3 

None. 



Referenced faults 
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Fault definitions 



New fault definitions for this service. 



9.1 Fault: PolicyException 

Busy criteria not supported. 



Name 


Description 


Message Id 


<POL0200> 


Text 


Busy criteria is not supported. 


Variables 


None. 



1 Service po icies 


Name 


Type 


Description 


BusyAvailable 


xsd:boolean 


Can busy be returned as a status or be a trigger 


IVIaximumNotificationAddresses 


xsd:int 


Maximum number of addresses for which a notification can be 
set up 


MaximumNotificationFrequency 


common:TimeMetric 


Maximum rate of notification delivery (also can be considered 
minimum time between notifications) 


MaximumNotification Duration 


common:TimeMetric 


Maximum amount of time a notification may be set up for 


IVIaximumCount 


xsd:int 


Maximum number of notifications that may be requested 


UnlimitedCountAllowed 


xsd:boolean 


Allowed to specify unlimited notification count (i.e. either by not 
specifying the optional Count message part in 
StartNotificationRequest or by specifying a value of zero) 


GroupSupport 


xsd:boolean 


Groups may be included with addresses 


NestedGroupSupport 


xsd:boolean 


Are nested groups supported in group definitions 
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Annex A (normative): 
WSDL for Terminal Status 



The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [6] and is 
contained in text files (contained in archive 29199-08-620-doclit.zip) which accompanies the present document. 
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Annex B (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


Dec 2003 


CN 21 


NP-030552 


-- 


-- 


Submitted to CN#22 for Information 


1.0.0 




Jan 2004 










Added The W3C WSDL representation of the APIs specified in the 
present document is contained in a set of files which accompany the 
present document: 

px0326rpcenc.zip 

px0326rpclit.zip 


1.0.1 




Jun 2004 


CN_24 


NP-040274 


- 


- 


Split into multi-part specification. 29.199-On, for n=1,2...9. 
Submitted to CN#24 for Information 


1.0.3 




Sep 2004 


CN 25 


NP-040360 


-- 


-- 


Draft v200 submitted to TSG CN#25 for Approval. 


2.0.0 


6.0.0 


Jun 2005 


CT 28 


CP-050221 


0001 


-- 


Optionals for Part 8 


6.0.0 


6.1.0 


Dec 2005 


CT 30 


CP-050573 


0002 


-- 


Make the CurrentStatus element an optional parameter 


6.1.0 


6.2.0 


Dec 2005 


CT 30 


CP-050573 


0003 


-- 


Allow list of addresses in StatusNotificationRequest 


6.1.0 


6.2.0 
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History 



Document history 


V6.0.0 


January 2005 


Publication 


V6.1.0 


June 2005 


Publication 


V6.2.0 


December 2005 


Publication 
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